Summary

• New psi-{provider}-setup.timer generated alongside the setup service, triggers the same unit on cache.refresh_interval (default 1h). Today only psi-infisical-setup.timer is emitted — nitrokeyhsm is local-only.
• Two new CacheConfig fields: refresh_interval and refresh_randomized_delay. Both accept systemd time strings.
• psi systemd install writes and enables the timer automatically when the cache is configured. Works for both native and container modes.
• Docs updated in docs/secret-cache.md, README.md, and CLAUDE.md.

Why

Before this PR, PSI populated the cache at boot and on lookup miss, and operators could run psi cache refresh manually. A secret rotated in Infisical between reboots stayed stale until someone intervened or the host restarted. Option (a) from the cache-sync design discussion was the lowest-effort fix: an external systemd timer that kicks the existing setup unit. This matches the existing pattern for psi-tls-renew.timer and keeps serve code untouched.

What changes

psi/settings.py

• CacheConfig.refresh_interval: str = "1h"
• CacheConfig.refresh_randomized_delay: str = "5m"

Both are passed straight through to systemd, so any valid systemd time string works (30m, 2h, 1d, etc.).

psi/unitgen.py

• generate_provider_setup_timer(provider, interval, randomized_delay) — builds a .timer unit targeting psi-{provider}-setup.service. Uses OnBootSec + OnUnitActiveSec + Persistent=true so the schedule survives reboots and missed intervals.
• provider_supports_refresh(provider) — returns True only for providers whose setup path talks to a remote. Set of one today: {"infisical"}.

psi/installer.py

• New _write_refresh_timers helper emits the timer for each refreshable provider. Returns early if cache.enabled is False or cache.backend is None — no point scheduling refreshes if PSI is not caching.
• _install_native and _install_container both call it. Timers live under the systemd unit dir in both modes (timers are plain units regardless of whether the triggered service comes from a quadlet).
• _enable_units gains a refresh_timers kwarg and enables each timer with systemctl enable --now when --enable is passed.

Tests

• tests/test_unitgen.py: TestProviderRefreshSupport (3 tests) and TestProviderSetupTimer (5 tests) covering the target unit, interval/delay pass-through, Persistent=true, the [Install] section, and the description text.
• tests/test_installer.py: TestWriteRefreshTimers (5 tests) covering the happy path, cache disabled, no backend configured, nitrokeyhsm-only providers, and custom interval.

Docs

• docs/secret-cache.md: rewrites the rotation section into "Rotation and periodic refresh" with three subsections — scheduled refresh (timer details, tuning via systemctl edit), manual refresh (CLI commands), and on-miss refill (what the serve process already does). Adds refresh_interval and refresh_randomized_delay to the configuration example.
• README.md: updates the cache config example to include the new fields, adds a paragraph about the auto-generated timer, adds psi-infisical-setup.timer to the FCOS generator list, and notes in the CLI reference that psi cache refresh is only needed for out-of-band rotations.
• CLAUDE.md: same CLI-reference note.

Test plan

• uv run ruff check psi/ tests/ — clean
• uv run ruff format --check psi/ tests/ — clean
• uv run ty check — clean
• uv run pytest -q — 309 passed (13 new tests)
• On a test server: pull the new image, regenerate quadlets, confirm psi-infisical-setup.timer exists and systemctl list-timers shows the next run at refresh_interval from boot
• Rotate a secret in Infisical, wait for the next scheduled refresh, confirm the new value is served via podman exec psi-secrets psi cache status --verify and an actual container lookup